/*
 * Copyright 2011 The Rusted Roof, LLC.
 *
 *    Licensed under the Apache License, Version 2.0 (the "License");
 *    you may not use this file except in compliance with the License.
 *    You may obtain a copy of the License at
 *
 *        http://www.apache.org/licenses/LICENSE-2.0
 *
 *    Unless required by applicable law or agreed to in writing, software
 *    distributed under the License is distributed on an "AS IS" BASIS,
 *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *    See the License for the specific language governing permissions and
 *    limitations under the License.
 */

package org.proteusframework.platformservice;

import org.proteusframework.core.api.model.INamespace;

/**
 * Extended platform service methods that provide custom service plugin scope management.
 *
 * @see ServiceScope
 */
public interface IScopedServiceDelegate
{
    /**
     * Requests an instance of a <i>custom</i> platform service using the specific scoping guidelines. Scoping is
     * managed entirely by the Proteus Platform Services, and not the specific plugin per se. However, each custom
     * service plugin may optionally declare specific scopes that it <i>cannot</i> support, effectively limiting the
     * ability of the platform to honor the requested scope.
     * <p/>
     * This method signature can only be used to request {@link ServiceScope#ApplicationSingleton} or
     * {@link ServiceScope#NewInstancePerRequest} scopes.
     *
     * @param expectedInterface Expected interface of the given platform service
     * @param scope             Requested scope of the returned instance
     * @param <T>               Specific type of custom service interface
     * @return Active instance of the specified platform service
     * @throws ServiceScopingException        when the scope request cannot be fulfilled
     * @throws ServiceNotInstalledException   when the custom service is not installed
     * @throws ServiceInitializationException when the service initialization fails
     */
    <T extends IServicePlugin> T getPlatformService(Class<T> expectedInterface, ServiceScope scope)
            throws ServiceScopingException;

    /**
     * Requests an instance of a <i>custom</i> platform service using the specific scoping guidelines. Scoping is
     * managed entirely by the Proteus Platform Services, and not the specific plugin per se. However, each custom
     * service plugin may optionally declare specific scopes that it <i>cannot</i> support, effectively limiting the
     * ability of the platform to honor the requested scope.
     * <p/>
     * This method signature can only be used to request any scope, but typically is used only for requesting either
     * {@link ServiceScope#FamilySingleton}, {@link ServiceScope#NamespaceSingleton}, and
     * {@link ServiceScope#ExtendedNamespaceSingleton} scopes.
     *
     * @param expectedInterface Expected interface of the given platform service
     * @param scope             Requested scope of the returned instance
     * @param namespace         Namespace to interrogate for family- or namespace-singleton requests
     * @param <T>               Specific type of custom service interface
     * @return Active instance of the specified platform service
     * @throws ServiceScopingException        when the scope request cannot be fulfilled
     * @throws ServiceNotInstalledException   when the custom service is not installed
     * @throws ServiceInitializationException when the service initialization fails
     */
    <T extends IServicePlugin> T getPlatformService(Class<T> expectedInterface, ServiceScope scope, INamespace namespace)
            throws ServiceScopingException;
}
